<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org">
<meta http-equiv="Content-Type" content=
"text/html; charset=iso-8859-1">
<meta name="resource-type" content="document">
<meta name="description" content=
"Understanding update issues in the ports tree">
<meta name="keywords" content="openbsd,ports,update">
<meta name="distribution" content="global">
<meta name="copyright" content=
"This document copyright 2006 by OpenBSD.">
<title>Understanding update issues in the ports tree</title>
</head>
<body text="Black" bgcolor="White" link="#23238E">
<img height="30" width="141" src="../images/smalltitle.gif" alt=
"[OpenBSD]"> 

<h1>The maintainer's guide to Updating ports</h1>

<p>Since OpenBSD 3.8, pkg_add can update packages. So maintainers have to
be aware of one simple fact: update is not instantaneous. Even if a user
just goes from release to release, each time they run pkg_add -ui, the
system will replace each package with a new version, one package at a time.
So the user will run a mixed system, even if it is for just a few minutes.
</p>

<p>There are basically two update models of which maintainers must be
aware.
</p>
<ul>
<li>Some users follow current on a loose basis. They update their packages
every few days/every few weeks. Either all packages, or only some selected
packages. The update mechanism should work for them: it can force them to
update some specific packages, or to install some new stuff, but it should
not fail silently.  Micro-updates must be tested.  These users will most
often be able to cope with small changes, like program name changes, or 
configuration adjustments.
<li>Some users update every six months with a new release. They also will
download stable updates (security and critical updates). During six months,
a large part of the ports tree changes.   These users do not care about
individual software changes. They just want a system that works.  Changing
binary names is completely unfriendly to these users.  Tweaking hundreds
of configuration files will be a major pain for them.
Maintainers can help by providing smooth update paths, and major hints
whenever something important changes.
</ul>

<p>You should note that part of the update process, especially the 
macroscopic changes for users who update every six months, is not yet
automated.  The global update mechanism is still a work in progress, and
pkg_add will be able to cope with more issues in the future.
As of now, you should focus on making sure the system updates
correctly, one port at a time, and that one port's update takes other ports
into account, as far as conflicts and other issues are concerned.
</p>

<h2>Naming packages and the update process</h2>
<h2>Conflicts, planning for the future</h2>
<h2>The icky business of renames and branches</h2>
<h2>Configuration files and update issues</h2>
<h2>Shared libraries issues</h2>
<h2>Update checklist</h2>
Part of the work is to be done when making the port itself.
<ul>
  <li>Make sure the software authors are aware of your tweaks to make it
  run on OpenBSD. You must endeavor to get OpenBSD patches into the next 
  release of the software. Otherwise, you can be prepared to rewrite most
  of your patches from scratch every release.
  <li>Make sure the software authors understand version numbering. If the
  distfiles do not contain any version numbers, or if they reference
  current stuff, communicate with the authors so that you can get some
  permanent urls.
  <li>Document work-arounds. This will help you remember to check whether
  they are still necessary when you try to update a port.
  <li>Document dependencies. Especially the stuff you don't use. Some ports
  can use external software that may not be available at the time of porting.
  Make sure you do not pick it up, and document it, so that you can update
  your port when this software becomes available later.
  <li>If the port uses libtool, copy its log verbatim as a basis for your
  <code>SHARED_LIBS</code> setup. This will help during updates.
  <li>Use <code>PLIST_DB</code> and build a database of packing-lists.
  This is useful to find out about forgotten package name bumps, and also
  to check for conflicts with older packages.
  <li>Make sure dependencies stay as loose as they can be. By default,
  RUN_ and LIB_DEPENDS will be satisfied by any version of a package.
  Do not insist on a given version unless you have to. Use minimal versions
  whenever possible.
</ul>
Ports often need minor updates without a new version upstream.
<ul>
  <li>Each port update needs a package name bump. Otherwise, the update
  mechanism for binary packages won't work. Anything that affects the binary
  package implies a bump. This includes <code>HOMEPAGE</code>, 
  <code>MAINTAINER</code> or description changes.
  <li>If the package does not build, no bump is needed: changes to restore
  a port to working order after it got broken do not warrant bumps.
  <li>Changes to make sure a port does not pick/does pick an external 
  dependency warrant a bump.
  <li>Changes in dependencies generally do not affect a port version number.
  The package system uses a signature mechanism such that a binary package
  is fully identified by its package names, plus the dependencies against
  which it was built, plus the version numbers of all shared libraries it
  contains.
</ul>

Part of the work will happen before the update itself.
<ul>
  <li>run <code>make patch</code> to have an initial copy of the port before 
  the update.
</ul>
And then the update.
<ul>
  <li>Edit the port's Makefile to grab the new version, run <code>make makesum</code> and <code>make patch</code> as a starting basis.
  <li>Once you've fixed patches that failed, run a full diff between the old
  and the new version to figure out exactly what changed.  Take notes, be
  prepared to revisit things later.
  <li>Do whatever porting work is necessary to get the new version to run
  under OpenBSD, adjust dependencies, change package contents, etc.
  <li>Double check shared library versions. For libtool-based ports, you have
  the shared_libs.log to check whether the software authors did significant
  changes. <em>Note well that this is not enough.</em> Most software authors
  do not really understand shared library issues. You have to read the full
  diff between the old and the new version, and bump library versions 
  accordingly.  When in doubt, bump the major version.
  <li>Be aware of conflicts with already built packages. For simple 
  updates, nothing needs to be done. If you split a package into several
  subpackages, make sure the subpackages have proper conflict annotations:
  they should usually conflict with the `old' single package.
  <li>Help the user. If some specific steps must be taken beyond 
  <code>pkg_add -ui</code>, make sure they are visible in the package.
  When your packaging policy changes, document it in the package description.
  For instance, if you move the documentation into a separate package for
  space constraints, the main package description should mention that the
  documentation is now available as a separate package.
</ul>
  <a href="../index.html"><img height=24 width=24 src=../back.gif border=0 alt=OpenBSD></a> 
  <a href="mailto:www@openbsd.org">www@openbsd.org</a>
<br><small>$OpenBSD: update.html,v 1.4 2006/11/05 18:19:20 espie Exp $</small>
 </body>
</html>
